---
type: integration
title: '@astrojs/mdx'
description: "Apprenez à utiliser l'intégration @astrojs/mdx dans votre projet Astro."
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/mdx/'
category: other
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'

Cette **[intégration Astro][astro-integration]** permet d'utiliser les composants [MDX](https://mdxjs.com/) et de créer des pages sous forme de fichiers `.mdx`.

## Pourquoi MDX ?

MDX vous permet [d'utiliser des variables, des expressions JSX et des composants dans du contenu Markdown](/fr/guides/markdown-content/#fonctionnalités-mdx-uniquement) dans Astro. Si vous avez du contenu existant rédigé en MDX, cette intégration vous permet d'intégrer ces fichiers à votre projet Astro.

## Installation

Astro inclut une commande `astro add` pour automatiser l'installation des intégrations officielles. Si vous préférez, vous pouvez [installer les intégrations manuellement](#installation-manuelle) à la place.

Exécutez l'une des commandes suivantes dans une nouvelle fenêtre de terminal.

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npx astro add mdx
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm astro add mdx
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn astro add mdx
    ```
  </Fragment>
</PackageManagerTabs>

Si vous rencontrez des problèmes, [n'hésitez pas à nous les signaler sur GitHub](https://github.com/withastro/astro/issues) et essayez les étapes d'installation manuelle ci-dessous.

### Installation manuelle

Tout d'abord, installez le paquet `@astrojs/mdx` :

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npm install @astrojs/mdx
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm add @astrojs/mdx
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn add @astrojs/mdx
    ```
  </Fragment>
</PackageManagerTabs>

Ensuite, appliquez l'intégration à votre fichier `astro.config.*` en utilisant la propriété `integrations` :

```js title="astro.config.mjs" ins={2} ins="mdx()"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
});
```

### Intégration dans un éditeur

Pour la prise en charge de l'éditeur dans [VS Code](https://code.visualstudio.com/), installez l'[extension MDX officielle](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx).

Pour les autres éditeurs, utilisez le [serveur de langage MDX](https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-server).

## Utilisation

Avec l'intégration MDX d'Astro, vous pouvez [ajouter des pages MDX à votre projet](/fr/guides/markdown-content/#pages-markdown-et-mdx) en ajoutant des fichiers `.mdx` dans votre répertoire `src/pages/`. Vous pouvez également [importer des fichiers `.mdx`](/fr/guides/markdown-content/#importer-du-contenu-markdown) dans des fichiers `.astro`.

L'intégration MDX d'Astro ajoute des fonctionnalités supplémentaires au MDX standard, y compris un texte frontal de style Markdown. Cela vous permet d'utiliser la plupart des fonctionnalités Markdown intégrées d'Astro comme une [propriété `layout` spéciale de frontmatter](/fr/guides/markdown-content/#frontmatter-layout).

Regardez comment MDX fonctionne dans Astro avec des exemples dans notre [Guide Markdown & MDX](/fr/guides/markdown-content/).

Visitez la [documentation MDX](https://mdxjs.com/docs/what-is-mdx/) pour apprendre à utiliser les fonctions MDX standard.

## Configuration

Une fois l'intégration MDX installée, aucune configuration n'est nécessaire pour utiliser les fichiers `.mdx` dans votre projet Astro.

Vous pouvez configurer le rendu de votre MDX à l'aide des options suivantes :

* [Options héritées de la configuration Markdown](#options-héritées-de-la-configuration-markdown)
* [`extendMarkdownConfig`](#extendmarkdownconfig)
* [`recmaPlugins`](#recmaplugins)
* [`optimize`](#optimize)

### Options héritées de la configuration Markdown

Toutes les [options de configuration `markdown`](/fr/reference/configuration-reference/#markdown-options) peuvent être configurées séparément dans l'intégration MDX. Cela inclut les plugins remark et rehype, la coloration syntaxique, et plus encore. Les options seront par défaut celles de votre configuration Markdown ([voir l'option `extendMarkdownConfig`](#extendmarkdownconfig) pour les modifier).

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypeMinifyHtml from 'rehype-minify-html';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypeMinifyHtml],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});
```

:::caution
MDX ne permet pas de fournir les plugins remark et rehype sous la forme d'une chaîne. Vous devez installer, importer et appliquer la fonction du plugin à la place.
:::

<ReadMore>Voir la [référence des options Markdown](/fr/reference/configuration-reference/#markdown-options) pour une liste complète des options.</ReadMore>

### `extendMarkdownConfig`

* **Type:** `boolean`
* **Default:** `true`

MDX étend par défaut [la configuration Markdown existante de votre projet](/fr/reference/configuration-reference/#markdown-options). Pour remplacer certaines options, vous pouvez spécifier leur équivalent dans votre configuration MDX.

Par exemple, disons que vous avez besoin de désactiver GitHub-Flavored Markdown et d'appliquer un ensemble différent de plugins de remark pour les fichiers MDX. Vous pouvez appliquer ces options comme suit, avec `extendMarkdownConfig` activée par défaut :

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // `syntaxHighlight` héritée de Markdown

      // Markdown `remarkPlugins` ignorée,
      // seulement `remarkPlugin2` est appliquée.
      remarkPlugins: [remarkPlugin2],
      // `gfm` remplacée par `false`
      gfm: false,
    }),
  ],
});
```

Vous pouvez également avoir besoin de désactiver l'extension de la configuration `markdown` dans MDX. Pour cela, mettez `extendMarkdownConfig` à `false` :

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // La configuration Markdown est désormais ignorée
      extendMarkdownConfig: false,
      // Pas de `remarkPlugins` appliquée
    }),
  ],
});
```

### `recmaPlugins`

Il s'agit de plugins qui modifient directement la sortie [estree](https://github.com/estree/estree). Ceci est utile pour modifier ou injecter des variables JavaScript dans vos fichiers MDX.

Nous vous suggérons [d'utiliser AST Explorer](https://astexplorer.net/) pour jouer avec les sorties d'estree, et d'essayer [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) pour effectuer des recherches dans les nœuds JavaScript.

### `optimize`

* **Type:** `boolean | { customComponentNames?: string[] }`

Il s'agit d'un paramètre de configuration facultatif qui permet d'optimiser la sortie MDX pour une construction et un rendu plus rapides grâce à un plugin rehype interne. Cela peut être utile si vous avez beaucoup de fichiers MDX et que vous constatez des lenteurs dans la construction. Cependant, cette option peut générer du HTML non échappé, assurez-vous donc que les parties interactives de votre site fonctionnent toujours correctement après l'avoir activée.

Cette option est désactivée par défaut. Pour activer l'optimisation MDX, ajoutez ce qui suit à votre configuration d'intégration MDX :

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});
```

#### `customComponentNames`

* **Type:** `string[]`

Une propriété optionnelle de `optimize` pour empêcher l'optimisateur MDX de gérer tout [composant personnalisé passé au contenu MDX importé via la propriété components](/fr/guides/markdown-content/#composants-personnalisés-avec-du-mdx-importé).

Vous devrez exclure ces composants de l'optimisation, car l'optimisateur convertit trop rapidement le contenu en une chaîne statique, ce qui brisera les composants personnalisés qui ont besoin d'être rendus dynamiquement.

Par exemple, la sortie MDX prévue pour ce qui suit est `<Heading>...</Heading>` à la place de chaque `"<h1>...</h1>"` :

```astro
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---

<Content components={{ ...components, h1: Heading }} />
```

Pour configurer l'optimisation à l'aide de la propriété `customComponentNames`, spécifiez un tableau de noms d'éléments HTML qui doivent être traités comme des composants personnalisés :

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // Empêcher l'optimisateur de traiter les éléments `h1`.
        // Ceux-ci seront traités comme des composants personnalisés
        customComponentNames: ['h1'],
      },
    }),
  ],
});
```

Notez que si votre fichier MDX [configure les composants personnalisés en utilisant `export const components = { ... }`](/fr/guides/markdown-content/#affectation-de-composants-personnalisés-à-des-éléments-html), alors vous n'avez pas besoin de configurer manuellement cette option. L'optimisateur les détectera automatiquement.

## Exemples

* Le [modèle de démarrage Astro MDX](https://github.com/withastro/astro/tree/latest/examples/with-mdx) montre comment utiliser les fichiers MDX dans votre projet Astro.

[astro-integration]: /fr/guides/integrations-guide/

[astro-ui-frameworks]: /fr/guides/framework-components/#utilisation-des-composants-de-framework
